@shapediver/sdk.sdtf-geometry

Structured Data Transfer Format - Integration for geometry types

The Structured Data Transfer Format (sdTF) is an API-neutral exchange and storage format for trees of data items as used by parametric 3D modeling software like Grasshopper®. This open, efficient, and easily extensible data format enables the exchange of complex data structures, independent of software vendors. See the sdTF documentation for more details.

The aim of this package is to extend the sdTF-v1 module to provide processing and typing functionality for geometric data.

It can be used in Node.js and modern Browsers, and exposes the respective TypeScript declarations.

Installation

npm i @shapediver/sdk.sdtf-v1 @shapediver/sdk.sdtf-geometry

This package is a plugin for the sdTF-v1 module and cannot be used by itself.

Usage

This code initializes the SDK and registers the integration for geometry types. After this step, the integration is fully included in all reading and writing processes of the SDK instance.

// index.ts
import { create, SdtfSdk } from "@shapediver/sdk.sdtf-v1"
import { SdtfGeometryTypeIntegration } from "@shapediver/sdk.sdtf-geometry"

(async () => {
    const sdk: SdtfSdk = await create({
        integrations: [ new SdtfGeometryTypeIntegration() ]
    })

    // Use the sdk here
})()

Supported types

The following table lists all type hints that are supported by this integration, their specific TypeScript types, and the provided type guard functions that can be used to infer a data content type.

Type hint name	TypeScript type	Type guard
"geometry.arc" or SdtfGeometryTypeHintName.GEOMETRY_ARC	SdtfGeometryArcType	SdtfGeometryTypeHintName.assertArc SdtfGeometryTypeHintName.isArc
"geometry.boundingbox" or SdtfGeometryTypeHintName.GEOMETRY_BOUNDING_BOX	SdtfGeometryBoundingBoxType	SdtfGeometryTypeHintName.assertBoundingBox SdtfGeometryTypeHintName.isBoundingBox
"geometry.box" or SdtfGeometryTypeHintName.GEOMETRY_BOX	SdtfGeometryBoxType	SdtfGeometryTypeHintName.assertBox SdtfGeometryTypeHintName.isBox
"geometry.circle" or SdtfGeometryTypeHintName.GEOMETRY_CIRCLE	SdtfGeometryCircleType	SdtfGeometryTypeHintName.assertCircle SdtfGeometryTypeHintName.isCircle
"geometry.complex" or SdtfGeometryTypeHintName.GEOMETRY_COMPLEX	SdtfGeometryComplexType	SdtfGeometryTypeHintName.assertComplex SdtfGeometryTypeHintName.isComplex
"geometry.cone" or SdtfGeometryTypeHintName.GEOMETRY_CONE	SdtfGeometryConeType	SdtfGeometryTypeHintName.assertCone SdtfGeometryTypeHintName.isCone
"geometry.cylinder" or SdtfGeometryTypeHintName.GEOMETRY_CYLINDER	SdtfGeometryCylinderType	SdtfGeometryTypeHintName.assertCylinder SdtfGeometryTypeHintName.isCylinder
"geometry.ellipse" or SdtfGeometryTypeHintName.GEOMETRY_ELLIPSE	SdtfGeometryEllipseType	SdtfGeometryTypeHintName.assertEllipse SdtfGeometryTypeHintName.isEllipse
"geometry.interval" or SdtfGeometryTypeHintName.GEOMETRY_INTERVAL	SdtfGeometryIntervalType	SdtfGeometryTypeHintName.assertInterval SdtfGeometryTypeHintName.isInterval
"geometry.interval2" or SdtfGeometryTypeHintName.GEOMETRY_INTERVAL2	SdtfGeometryInterval2Type	SdtfGeometryTypeHintName.assertInterval2 SdtfGeometryTypeHintName.isInterval2
"geometry.line" or SdtfGeometryTypeHintName.GEOMETRY_LINE	SdtfGeometryLineType	SdtfGeometryTypeHintName.assertLine SdtfGeometryTypeHintName.isLine
"geometry.matrix" or SdtfGeometryTypeHintName.GEOMETRY_MATRIX	SdtfGeometryMatrixType	SdtfGeometryTypeHintName.assertMatrix SdtfGeometryTypeHintName.isMatrix
"geometry.plane" or SdtfGeometryTypeHintName.GEOMETRY_PLANE	SdtfGeometryPlaneType	SdtfGeometryTypeHintName.assertPlane SdtfGeometryTypeHintName.isPlane
"geometry.point" or SdtfGeometryTypeHintName.GEOMETRY_POINT	SdtfGeometryPointType	SdtfGeometryTypeHintName.assertPoint SdtfGeometryTypeHintName.isPoint
"geometry.polyline" or SdtfGeometryTypeHintName.GEOMETRY_POLYLINE	SdtfGeometryPolylineType	SdtfGeometryTypeHintName.assertPolyline SdtfGeometryTypeHintName.isPolyline
"geometry.ray" or SdtfGeometryTypeHintName.GEOMETRY_RAY	SdtfGeometryRayType	SdtfGeometryTypeHintName.assertRay SdtfGeometryTypeHintName.isRay
"geometry.rectangle" or SdtfGeometryTypeHintName.GEOMETRY_RECTANGLE	SdtfGeometryRectangleType	SdtfGeometryTypeHintName.assertRectangle SdtfGeometryTypeHintName.isRectangle
"geometry.sphere" or SdtfGeometryTypeHintName.GEOMETRY_SPHERE	SdtfGeometrySphereType	SdtfGeometryTypeHintName.assertSphere SdtfGeometryTypeHintName.assertSphere
"geometry.torus" or SdtfGeometryTypeHintName.GEOMETRY_TORUS	SdtfGeometryTorusType	SdtfGeometryTypeHintName.assertTorus SdtfGeometryTypeHintName.isTorus
"geometry.transform" or SdtfGeometryTypeHintName.GEOMETRY_TRANSFORM	SdtfGeometryTransformType	SdtfGeometryTypeHintName.assertTransform SdtfGeometryTypeHintName.isTransform
"geometry.vector" or SdtfGeometryTypeHintName.GEOMETRY_VECTOR	SdtfGeometryVectorType	SdtfGeometryTypeHintName.assertVector SdtfGeometryTypeHintName.isVector

Additionally, the type guard SdtfGeometryTypeHintName provides functions to infer subtypes of SdtfGeometryPointType and SdtfGeometryVectorType:

typeGuard.assertPoint2d and typeGuard.isPoint2d:
Infer the subtype SdtfGeometryPoint2d of SdtfGeometryPointType.

typeGuard.assertPoint3d and typeGuard.isPoint3d:
Infer the subtype SdtfGeometryPoint3d of SdtfGeometryPointType.

typeGuard.assertPoint4d and typeGuard.isPoint4d:
Infer the subtype SdtfGeometryPoint4d of SdtfGeometryPointType.

typeGuard.assertVector2d and typeGuard.isVector2d:
Infer the subtype SdtfGeometryVector2d of SdtfGeometryVectorType.

typeGuard.assertVector3d and typeGuard.isVector3d:
Infer the subtype SdtfGeometryVector3d of SdtfGeometryVectorType.

Example

This simple example reads a sdTF file and extracts the content of all data items. Every content data that is of a cylindrical or spherical type is scaled up and shown on the console.

// index.ts
import { create, SdtfSdk } from "@shapediver/sdk.sdtf-v1"
import { SdtfGeometryTypeIntegration, SdtfGeometryTypeGuard } from "@shapediver/sdk.sdtf-geometry"

(async () => {
    const sdk: SdtfSdk = await create({
        integrations: [ new SdtfGeometryTypeIntegration() ]
    })

    // Reads a sdTF file
    const asset = await sdk.createParser().readFromFile("./test.sdtf")

    // Process all data items with a cylindrical or spherical content
    for (const dataItem of asset.items) {
        const geometry = await dataItem.getContent()            // load data content of type `unknown`

        if (SdtfGeometryTypeGuard.isCylinder(geometry)) {       // checks and infers the type to `SdtfGeometryCylinderType`
            geometry.baseCircle.radius *= 5
        }
        else if (SdtfGeometryTypeGuard.isSphere(geometry)) {    // checks and infers the type to `SdtfGeometrySphereType`
            geometry.radius *= 7
        }
        else {
            continue
        }

        console.log("The scaled geometry is", geometry)         // Print out the scaled geometry information
    }
})()

Support

If you have questions, please use the ShapeDiver Help Center.

You can find out more about ShapeDiver right here.

Licensing

This project is released under the MIT License.